/// # System API 模块
///
/// 提供系统管理相关的 HTTP API 接口，包括：
/// - 用户管理
/// - 角色管理
/// - 权限管理
/// - 认证管理
///
/// ## 使用示例
///
/// ```rust
/// use utils::rpc::RpcConfig;
/// use apps_system::api::router::create_api_routes;
/// 
/// #[tokio::main]
/// async fn main() {
///     // 使用默认配置
///     let routes = create_api_routes(None);
///     
///     // 或使用自定义配置
///     let custom_config = Some(RpcConfig::default());
///     let routes = create_api_routes(custom_config);
/// }
/// ```

pub mod controller;
pub mod router;
pub mod model;

// 导出主要的API组件
pub use router::{create_api_routes, system_routes};
pub use controller::{RoleController, create_role_controller};

/// API模块使用示例
/// 
/// ```rust
/// use salvo::prelude::*;
/// use system::api::create_api_routes;
/// use system::config::RpcConfig;
/// 
/// #[tokio::main]
/// async fn main() {
///     // 创建API路由，使用默认RPC配置
///     let api_router = create_api_routes(None);
///     
///     // 或者使用自定义RPC配置
///     let custom_config = Some(RpcConfig::default());
///     let api_router_with_config = create_api_routes(custom_config);
///     
///     // 创建完整的应用路由
///     let app = Router::new()
///         .push(api_router)
///         .push(Router::with_path("health")
///             .get(health_check));
///     
///     // 启动服务器
///     let acceptor = TcpListener::new("0.0.0.0:5800").bind().await;
///     Server::new(acceptor).serve(app).await;
/// }
/// 
/// #[handler]
/// async fn health_check() -> &'static str {
///     "OK"
/// }
/// ```
/// 
/// ## 支持的API端点
/// 
/// ### 角色管理
/// - `GET /api/system/roles` - 获取角色列表
/// - `POST /api/system/roles` - 创建角色  
/// - `GET /api/system/roles/{role_id}` - 获取角色详情
/// - `PUT /api/system/roles/{role_id}` - 更新角色
/// - `DELETE /api/system/roles/batch` - 批量删除角色
/// - `GET /api/system/roles/tree` - 获取角色树
/// - `POST /api/system/roles/bind-user` - 用户绑定角色
/// 
/// ### 认证管理
/// - `GET /api/system/auth/captcha` - 获取验证码
/// - `POST /api/system/auth/login` - 用户登录
/// 
/// ## 模型结构
/// 
/// 所有的请求和响应模型都使用了 `endpoint_derive_for` 宏：
/// - `usage = "query"` 用于查询参数
/// - `usage = "body"` 用于请求体
/// - `usage = "response"` 用于响应体
/// 
/// 并且包含了适当的验证注解，如：
/// ```rust
/// #[validate(length(min = 1, message = "角色名称不得为空"))]
/// pub name: String,
/// ```
/// 
/// 这样就完成了API与RPC的完整对接！
pub struct ApiDocumentation;